================================================================================
        AI 自动化经营闭环 — API 接入及测试方法参考
        （LightAIP + LightFoundry + OAG 跨产品）
================================================================================

日期：2026-08-11
来源：action/release/v2026.08.09/api-demo 下 sence/（场景脚本）与
      testing-result/（测试报告）全套文档整理汇总。
适用：S01-S12 AI 自动化经营场景的 API 接入、工作流构建、测试执行与断言。

--------------------------------------------------------------------------------
目录
--------------------------------------------------------------------------------
1. 概述与闭环链路
2. 环境与服务架构
3. 认证方式
4. Foundry API 接入
5. AIP API 接入
6. 工作流定义规范（节点 / 模板 / 触发器过滤器）
7. 测试通用执行流程
8. 测试经验与陷阱（B1-B7 及通用经验）
9. 十二场景清单
10. 脚本结构与运行方式
11. 测试报告产出规范

================================================================================
1. 概述与闭环链路
================================================================================
本测试体系对标 Palantir Foundry/AIP 真实客户案例，映射到本项目
（LightAIP + LightFoundry + OAG 跨产品）已实现的"AI 自动化经营"闭环能力。

核心闭环链路（每场景验证目标）：

    Foundry 本体动作写库
        -> object_change_events 对象变化事件
        -> AIP EventScheduler 轮询（poll_interval=30s）
        -> event 工作流触发
        -> ai_analysis LLM 决策
        -> condition 分支路由（可选）
        -> execute_foundry_action 自动执行动作
        -> 业务数据落库变化 + Foundry 审计 + AIP 通知（WORKFLOW_NOTIFICATION）

"外部事件 / 信息变化 / 手动操作 → 自动预警 → AI 决策 → 自动执行 → 审计/通知"
符合预期即视为闭环验证通过。

================================================================================
2. 环境与服务架构
================================================================================
2.1 服务清单（复用已启动服务）

    产品      端口    关键配置                                   平台库
    ---------------------------------------------------------------
    AIP      18080   OAG 启用（foundry.oag.enabled=true）         temp/ai_auto_env/aip/temp/aip_platform.db
    Foundry  18081   secret_key 与 AIP 一致（HS256 跨产品验签）   temp/ai_auto_env/foundry/temp/foundry_platform.db
    Apollo   18082   -                                          temp/ai_auto_env/apollo/temp/apollo_platform.db
    Gotham   18083   -                                          temp/ai_auto_env/gotham/temp/gotham_platform.db
    Swift    18084   -                                          temp/ai_auto_env/swift/temp/swift_platform.db

    （S01-S11 主用 AIP + Foundry；Apollo/Gotham/Swift 本测试不使用）

2.2 demo 数据源
    - 名称：foundry_demo_warehouse（AIP 中另有 foundry_demo_wh，data_source_id=2，
      指向同一 demo 库，供 query_data 节点使用）
    - 数据库：SQLite  temp/ai_auto_env/foundry/temp/foundry_demo.db
    - 基础表：customers / orders / products / inventory / purchase_requests
    - 扩展对象（S05-S11 新增）：production_lines / product_prices / equipment /
      work_orders / suppliers / risk_events / staff_shifts / supply_items / quotes

2.3 服务启动注意
    - bash cwd 每次重置，命令需带 cd /f/chatBI/chatBI_dev 前缀。
    - 停止进程必须用 PowerShell（bash taskkill 经 WOW64 无法杀 64 位进程）。
    - 如重建 demo 库或重启服务：PowerShell 停进程 -> 重新 seed -> 再启动。
    - AIP 启动日志应确认「工作流 event 触发器轮询调度器已启动 poll_interval=30s」。

================================================================================
3. 认证方式
================================================================================
统一账号：admin / admin1

    POST /api/v1/auth/login
    Body: {"username":"admin","password":"admin1"}

响应差异（务必注意）：
    - AIP：token 在响应顶层  -> d["token"]
    - Foundry：token 在 data 内 -> d["data"]["token"]

后续所有请求头携带：Authorization: Bearer <token>

================================================================================
4. Foundry API 接入
================================================================================
4.1 执行本体动作（触发事件 / 写库）
    POST /api/v1/ontology/actions/:action_name/execute
    Body:
    {
      "action_name": "update_inventory",
      "object_type_id": 4,
      "params": {
        "inventory_id": 1, "stock_level": 30, "product_id": 1,
        "reorder_point": 50, "expected_updated_at": "2026-08-11 09:00:00.000"
      },
      "idempotency_key": "s01-main-1723330000000",
      "mode": "VALIDATE_AND_EXECUTE"
    }
    返回：200 + code=0 表示执行成功。
    要点：
    - 触发动作额外附带的业务上下文参数（如 product_id/reorder_point/prev_price/
      credit_score/amount 等非 schema 字段）会被 Foundry 接受并写入事件 params，
      供工作流 condition 与 ai_analysis 使用。
    - idempotency_key 需唯一（常用 "场景-{time_ms}"）。
    - 更新类动作（乐观锁）必须传 expected_updated_at（见 8.2 LOCK_RESET）。

4.2 对象变化事件（轮询）
    GET /api/v1/ontology/change-events?after_id=<上次最大id>&limit=100
    返回 data.events 数组；每事件含 id / object_type_name / action_name /
    object_id / params_json。
    注意：create 类动作（如 create_quote/create_purchase_request）的事件
    object_id 为空、params 不含自增主键。

4.3 审计
    GET /api/v1/audit/events?page=1&page_size=50
    记录本体动作执行审计。

4.4 已知对象类型（id 稳定，S01-S11 使用）
    id   name            表                   动作
    ---  ---------------  -------------------  --------------------------------
    1    customer        customers            update_customer_credit
    2    order           orders               update_order_status / flag_order_risk
    3    product         products             -
    4    inventory       inventory            update_inventory
    5    purchase_request purchase_requests   create_purchase_request
    6    production_line production_lines     update_production_line
    7    product_price   product_prices       update_product_price
    8    equipment       equipment            update_equipment_reading
    9    work_order      work_orders          create_work_order
    10   supplier        suppliers            update_supplier_status
    11   risk_event      risk_events          create_risk_event
    12   staff_shift     staff_shifts         update_shift_load
    13   supply_item     supply_items         update_delivery_status
    14   quote           quotes               create_quote / approve_quote

================================================================================
5. AIP API 接入
================================================================================
5.1 工作流管理
    POST   /api/v1/workflows                     创建（201 + data.id）
    POST   /api/v1/workflows/:id/publish         发布（data.status=published）
    POST   /api/v1/workflows/:id/unpublish       停用
    DELETE /api/v1/workflows/:id                 删除
    GET    /api/v1/workflows?page=&page_size=    列表

    创建 Body：
    {
      "name": "S01-库存补货自动化-...",
      "description": "S01 库存补货自动化",
      "definition": { "nodes": [...], "edges": [...] },   // 见第 6 章
      "trigger_config": { "type": "event", "filters": {...} } // 见 6.4
    }

5.2 工作流执行
    POST /api/v1/workflows/:id/run               手动触发
         Body: {"params": {...}}  （params 作为 .trigger 上下文注入）
    GET  /api/v1/workflows/:id/executions        执行列表
    GET  /api/v1/workflows/executions/:eid       执行详情（节点 outputs/status）

    执行详情结构：
    - data.execution.status（completed/failed/...）
    - data.nodes[]：node_id / node_type / status / output_json / error
    - data.execution.trigger_data_json：触发数据（事件 id 需 JSON 解析提取）

5.3 审计日志（通知信号）
    GET /api/v1/audit/logs?page=1&page_size=100
    send_notification 节点执行后产生 event_type=WORKFLOW_NOTIFICATION 记录，
    subject 在 action_details 中，断言按场景名关键字过滤。

5.4 Automation Copilot（S12 专项）
    POST /api/v1/automation/chat   SSE 流式
         Body: {"session_id":"s12a","message":"每天 8 点自动检查库存，低于补货点的自动补货并通知我"}
         SSE 事件：reasoning（DeepSeek thinking）/ tool_call / tool_result
         工具：create_automation（cron/event 工作流）、execute_action、
               query_objects、list_change_events、run_automation_now
    GET  /api/v1/automation/sessions/:id          会话落库查询
    落库：automation_sessions / automation_messages / workflows / audit_log

================================================================================
6. 工作流定义规范
================================================================================
6.1 节点类型
    - trigger：{type:"trigger", config:{trigger_type:"manual"|"event"|"cron"}}
    - ai_analysis：{type:"ai_analysis", config:{prompt_template:"..."}}
        触发上下文注入：{{json .trigger.event}} / {{.trigger.xxx}}；
        输出在 analysis 节点 output_json/output.text（断言 AI 决策）。
    - condition：{type:"condition", config:{
        condition_template:"{{if lt .trigger.stock_level .trigger.reorder_point}}true{{else}}false{{end}}",
        true_branch:"节点id", false_branch:"节点id"}}
    - query_data：{type:"query_data", config:{data_source_id:2, sql_template:"SELECT * FROM orders WHERE order_id={{.trigger.order_id}}"}}
        输出在 .q.output.rows（二维数组），引用：{{index (index .q.output.rows 0) 5}}。
    - execute_foundry_action：{type:"execute_foundry_action", config:{
        action_name, object_type_id, params:{...}, idempotency_key, mode:"VALIDATE_AND_EXECUTE"}}
    - send_notification：{type:"send_notification", config:{subject_template, body_template}}

6.2 edges（有向边）
    [{"from":"t0","to":"analysis"},{"from":"analysis","to":"condition"}, ...]
    条件节点由 true_branch/false_branch 决定路由，无需额外边。

6.3 模板语法（Go text/template）
    - {{json .trigger.event}}                    事件整体 JSON 注入 prompt
    - {{.trigger.event.id}}                      事件 id
    - {{.trigger.event.params.stock_level}}      事件参数（数值为 float64）
    - {{.trigger.event.object_id}}               对象 id（create 动作可能为空）
    - {{.trigger.order_id}}                      手动触发 params 字段
    - {{.q.output.rows}} / {{index (index .q.output.rows 0) 0}}   query_data 结果
    - 条件比较：数值用浮点字面量 eq ... 1.0 / lt ... 10000.0；
                字符串用引号 eq .trigger.event.action_name "update_inventory"

6.4 trigger_config 过滤器（B6 修复后可用，强烈建议）
    event 工作流务必配置过滤器，阻断"自动动作事件"自触发：
    {"type":"event",
     "filters":{"object_types":["equipment"],"action_names":["update_equipment_reading"]}}
    注意：若自动动作与触发使用同一 action_name（如 S09/S10），filters 无法阻断，
    必须叠加 condition 参数守卫（见 8.5）。

================================================================================
7. 测试通用执行流程
================================================================================
每场景统一六步：
    1. 初始化数据：python sqlite3 直写 temp/ai_auto_env/foundry/temp/foundry_demo.db，
       构造前置状态（主行 + 对照行），记录目标行 updated_at。
    2. 创建工作流：POST /api/v1/workflows（含 B6 filters）-> POST /:id/publish。
    3. 触发：
       - event 触发：POST /api/v1/ontology/actions/:name/execute（写路径自动落
         object_change_events）；触发参数附带业务上下文供 LLM 决策。
       - 手动触发：POST /api/v1/workflows/:id/run。
    4. 等待：EventScheduler 30s 轮询；事件执行等待超时统一 ≥200s（容忍 LLM 延迟尖峰）。
    5. 断言（见下）：验证"事件 -> 执行 -> AI 决策 -> 自动执行 -> 业务数据 + 审计 + 通知"。
    6. 清理：unpublish + delete 工作流（防事件串扰；多场景必须串行）。

断言要点（落盘/明细，不只断言 HTTP 200）：
    - 事件出现：change-events after_id 轮询，匹配 object_id 与 action_name。
    - 工作流执行：executions 中按 trigger_data.event.id 精确匹配（JSON 解析），status=completed。
    - AI 决策：execution_detail 的 analysis 节点 output 含关键 JSON 字段（如 "decide":true）。
    - 动作落库：直查 foundry_demo.db 业务表（新增/更新行 + 字段值）。
    - 通知/审计：AIP audit/logs 含 WORKFLOW_NOTIFICATION（subject 含场景关键字）。
    - 对照用例：对照触发后业务数据不变 + action 节点 skipped 或走 false 分支。

================================================================================
8. 测试经验与陷阱（B1-B7 及通用经验）
================================================================================
8.1 B1 动作 SQL 模板强制可选参数（产品缺陷）
    update_product_price 等动作 SQL 模板含可选字段占位符，缺省传参会报
    HTTP 400 WRITE_CONFIG_ERROR missing value；risk_flag 为布尔，传数字 0 报 422。
    规避：触发/自动动作按 schema 完整传参；布尔字段传 true/false。
    验证状态：B1 相关触发传参已按此规则修复，S08/S10 布尔传参正常。

8.2 B5 乐观锁 updated_at 格式不一致 -> LOCK_RESET 方案（关键）
    query_data 读出的 updated_at 为 RFC3339（2026-08-11T09:00:00Z），而 SQLite
    存储格式为空间分隔（2026-08-11 09:00:00.000），乐观锁 WHERE updated_at=
    expected_updated_at 字面比较不一致 -> 409 ACTION_CONFLICT。
    规避（LOCK_RESET）：
        1) 触发动作写库后，立即直写 SQLite 把目标行 updated_at 重置为已知值 T0；
        2) 工作流 action 节点用该已知值作字面量 expected_updated_at；
        3) 更新动作执行即成功。create 类动作无乐观锁，无需处理。
    注意：probe_b5_lock.py 已验证「RFC3339 期望 vs 空间分隔存储」不再误报 409
    （时间等价判断生效），真实过期仍 409。

8.3 B3 条件模板数值比较类型不匹配
    事件 params 由 JSON 解析为 float64，与整型字面量 1 比较 eq 失败恒 false。
    规避：数值比较统一用浮点字面量 eq ... 1.0 / lt ... 10000.0；
          或 {{eq (printf "%v" .x) "1"}}；字符串比较用 "pending" 形式。

8.4 B4 execute_foundry_action 模板数值参数被字符串化
    action params 用 "{{.trigger.event.params.x}}" 引用数值时渲染为字符串 "1"，
    Foundry 数值校验报 422 expected type number, got string。
    规避：数值字段用字面量（JSON 数字）；字符串字段（expected_updated_at/
          status/risk_reason）用字面量或模板；query_data 渲染的主键可引用
          {{index (index .q.output.rows 0) 0}}（数值推断已生效）。

8.5 B6 event 工作流无对象/来源过滤 -> 自动动作事件自触发循环
    工作流自动执行的动作写库后生成新事件，又会触发同一 event 工作流。
    规避：
        - 配置 trigger_config.filters（object_types + action_names）阻断异名自动事件；
        - 自动动作与触发同 action_name 时（S09/S10），用 condition 参数守卫
          区分外部触发参数与自动动作参数（如 load==9.0、risk_flag==false）。
    经验：工作流测完立即 unpublish+delete；多场景串行。

8.6 B2 SQL 安全校验 naive 子串误报
    query_data 执行 SELECT ... WHERE 含列名 updated_at 会命中关键字 UPDATE 子串
    被拦截（forbidden SQL operation）。
    规避：query_data 避免列名含 UPDATE/INSERT/DELETE 子串，
          可用 SELECT * 按列索引取 updated_at。

8.7 B7 LLM 决策依赖触发参数上下文
    事件只携带触发请求 params；业务判断所需上下文（prev_price/credit_score/
    credit_limit/amount 等）需在触发时附带，否则 LLM 决策失真。
    规避：触发请求附加业务上下文参数供 ai_analysis 决策。

8.8 通用测试经验（S01-S11 实测）
    1) 事件匹配必须 JSON 解析：executions 的 trigger_data_json 含日期"2026-08-11"，
       子串匹配事件 id 会误匹配（"11"命中日期）；统一
       json.loads(trigger_data_json)["event"]["id"] 精确比较。
    2) 执行等待超时 ≥200s：EventScheduler 30s 轮询一次，但 ai_analysis LLM
       节点（deepseek thinking）耗时可能数十秒到 2 分钟，95s 超时会误判失败。
    3) create 动作事件无自增主键：create_quote/create_purchase_request 事件
       object_id 为空；需 query_data 动态取最新主键再驱动后续乐观锁动作（S11）。
    4) condition 节点不支持 contains：只能 true/false/==/!=；"AI 输出含
       decide:true"这类判断不可用，沿用确定性事件参数守卫 + analysis 输出
       单独断言的模式。
    5) 受影响区域模拟：orders 表无 region 列时用 customers.region
       （order->customer）模拟，LLM prompt 内嵌映射上下文（S08）。
    6) 通知信号：send_notification 落 AIP audit/logs，event_type=
       WORKFLOW_NOTIFICATION，断言按场景名关键字过滤。
    7) 时间预算：每场景含 2 次触发 + 2 次事件轮询 + 2 次 LLM 调用，
       单场景约 1.5-3 分钟（偶发 LLM 延迟可能更久）。

================================================================================
9. 十二场景清单
================================================================================
    场景  名称                  对标案例            触发方式            核心断言
    ----  --------------------  ------------------  ------------------  ------------------------------------------
    S01   库存补货自动化         Lowe's 供应链       event(update_inventory) 库存低于 reorder_point -> AI -> create_purchase_request + 通知
    S02   订单履行自动化         Acrisure 理赔       event(update_order_status) 新订单 -> AI 审核 -> update_order_status + 通知
    S03   客户信用风险自动管控   GNP 欺诈检测        event(update_customer_credit/大额订单) 订单超限 -> AI -> flag_order_risk/调低额度 + 通知财务
    S04   供应链中断应急         Navy ShipOS         event(update_supplier_status) 供应商中断 -> AI 应急 -> 多动作联动 + 通知
    S05   产线动态平衡           Lear 产线平衡       event(update_production_line) 负荷超阈值 -> AI 重排 -> update_production_line + 通知
    S06   价格暴露与风险标记     Lear 关税管理       event(update_product_price) 价格波动超阈值 -> AI 评估 -> flag 高风险 + 通知
    S07   设备预测性维护         bp/能源数字孪生     event(update_equipment_reading) 异常读数 -> AI 诊断 -> create_work_order + 通知
    S08   灾害应急响应           公用事业野火响应    event(create_risk_event) 灾害事件 -> AI 评估 -> 标记受影响资源 + 通知
    S09   临床排班优化           医院 ER/排班        event(update_shift_load) 负荷失衡 -> AI 排班建议 -> update_shift_load + 通知
    S10   材料审查与交付重排     Navy 材料审查       event(update_delivery_status) 交付延迟 -> AI 重排 -> 标记 + 通知
    S11   报价周期加速           Rackspace 太阳能    event(create_quote) 新询价 -> AI 生成报价 -> 自动审批 + 通知
    S12   Copilot 自动配置自动化 AIP Agent Studio   Copilot 对话 toolcall 对话自动创建 cron/event 工作流 + execute_action 完成业务操作

    已测结果：S01-S11 全部场景 138/138 用例 PASS（S01-S06 74/74，S07-S11 64/64）；
    S12 为 Copilot 对话专项（复用 temp/smoke_ai_automation.py 15/15 已验证基座）。

================================================================================
10. 脚本结构与运行方式
================================================================================
目录：action/release/v2026.08.09/api-demo/sence/（历史版本已随 release 归档；
      common.py 内 sys.path 指向 action/temp/sence/ 的运行副本）

    文件                      作用
    ------------------------  ---------------------------------------------------
    common.py                 公共库：HTTP（urllib）、登录、工作流 CRUD/run、
                              executions、审计、SQLite 直查、事件匹配/等待工具
    probe_*.py                单项能力探针（快速验证单个机制，运行后自清理）：
        probe_b5_lock.py      B5 乐观锁 RFC3339 归一直接验证
        probe_condition.py    condition 模板路由验证
        probe_lockreset.py    LOCK_RESET 模式验证
        probe_params.py       模板数值参数渲染验证
        probe_querydata.py    query_data 动态取 updated_at 验证
        probe_s11_q.py        S11 关键链路（create_quote 无主键 + query_data 取主键 + approve）
    s01_restock.py            S01 库存补货自动化场景脚本
    s02_order_fulfill.py      S02 订单履行自动化
    s03_credit_risk.py        S03 客户信用风险自动管控
    s04_supply_emergency.py   S04 供应链中断应急
    s05_line_balance.py       S05 产线动态平衡
    s06_price_risk.py         S06 价格暴露与风险标记
    s07_equipment_predictive.py S07 设备预测性维护
    s08_disaster_response.py  S08 灾害应急响应
    s09_shift_scheduling.py   S09 临床排班优化
    s10_material_review.py    S10 材料审查与交付重排
    s11_quote_acceleration.py S11 报价周期加速
    v4/                       S01-S12 场景设计文档（00_总览.md + SXX_*.md）

运行方式：
    cd /f/chatBI/chatBI_dev/action/temp/sence
    python s01_restock.py
    （退出码 0 = 全部用例 PASS；1 = 存在 FAIL）
    注意：common.py 中 DEMO_DB/AIP_DB 路径为绝对路径，环境变更时需同步修改。

公共库关键函数（common.py）：
    login_foundry() / login_aip()          登录取 token
    exec_action(f_token, action_name, object_type_id, params, idempotency_key, mode)  执行本体动作
    list_change_events(f_token, after_id, limit)  轮询事件
    audit_events(f_token)                  Foundry 审计
    create_workflow / publish_workflow / unpublish_workflow / delete_workflow / list_workflows
    list_executions / execution_detail     执行列表与详情
    run_workflow(a_token, wf_id, params)   手动触发
    audit_logs(a_token)                    AIP 审计日志（通知信号）
    query / exec_sql / demo / aip          SQLite 直查与直写（落盘断言）
    wait_for(pred, timeout, interval)      轮询等待
    max_event_id / find_exec_by_event / wait_exec_by_event / node_output / node_status
        事件游标、按事件精确匹配执行、节点输出/状态提取

================================================================================
11. 测试报告产出规范
================================================================================
每场景报告（见 testing-result/sence/v4/SXX_*.md）包含：
    1. 环境：服务地址、demo 库路径、登录方式、事件轮询确认。
    2. 场景设计：一句话业务链路。
    3. 初始化数据快照（SQL）：主行 + 对照行，含 updated_at。
    4. 工作流定义摘要：nodes 链、analysis prompt、condition 模板、action 参数。
    5. 用例表：步骤 | 入参 | 预期 | 实际 | 结果（PASS/FAIL）。
    6. 信号断言表：事件 / AI 决策 / 自动执行 / 审计 / 通知 各信号断言与结果。
    7. 不符合预期项与修复记录。
    8. 说明（使用到的规避技巧，如 LOCK_RESET / filters / 上下文参数）。

汇总文档：testing-result/sence/v4/S01-S06_汇总.md、S07-S11_汇总.md、
经验与问题汇总.md（B1-B7 产品缺陷清单 + 测试方法经验）。

--------------------------------------------------------------------------------
（完）
--------------------------------------------------------------------------------
